home *** CD-ROM | disk | FTP | other *** search
/ Night Owl 6 / Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso / 039a / pdxpp.zip / PDXPP.TXT < prev   
Text File  |  1990-06-28  |  17KB  |  572 lines
  1.              PDXPP -- The Paradox Class Libraries for C++
  2.                        Functional Documentation
  3.  
  4.  
  5.    Overview
  6.  
  7.    The PDXPP class library allows the programmer to access the
  8.    Paradox Engine using C++ class objects.  This not only allows the
  9.    programmer to maintain an object-oriented programming approach,
  10.    but also hides many of the mundane tasks of using the Paradox
  11.    Engine.
  12.  
  13.    The PDXPP class library was written by Gary B. Weinfurther.  It
  14.    is released into the public domain.  No warranties, expressed or
  15.    implied, are given with the library.  The author is not
  16.    responsible for the results, or lack therof, obtained from the
  17.    use or disuse of this library.
  18.  
  19.    There are five classes within the PDXPP library:
  20.  
  21.       PXOBJ     - Abstract base class for the other PDXPP classes.
  22.       PXTABLE   - Table-based operations.
  23.       PXFIELD   - Field-based operations.
  24.       PXRECORD  - Operations with record transfer buffers.
  25.       PXLOCK    - Record-locking operations.
  26.  
  27.    This documentation, as well as this library, assumes prior
  28.    knowledge of C++ and of the Paradox Engine.  In fact, this
  29.    library does not attempt to replace the entire functionality of
  30.    the Paradox Engine; doing so would not be of any necessary
  31.    benefit to the programmer.  Instead, the purpose of the PDXPP
  32.    library is to allow the manipulation of tables, fields, and
  33.    records through C++ objects.
  34.  
  35.    Not all of the functions within the Paradox Engine have
  36.    corresponding functions in this library.  Primarily, those
  37.    functions which manipulate the Paradox Engine environment or
  38.    perform file-level operations are not duplicated, and should be
  39.    called directly.  A list of these functions is given in Appendix
  40.    1.
  41.  
  42.    Class PXOBJ
  43.  
  44.    This is the base class of all of the PDXPP classes.  It provides
  45.    an error-checking mechanism and a table handle for all derived
  46.    classes.  Member functions include:
  47.  
  48.  
  49.    TABLEHANDLE TblHandle();
  50.  
  51.        Returns the table handle of the object.
  52.  
  53.  
  54.    int Result();
  55.  
  56.        Returns the error code of the last operation on this object.
  57.        This is a Paradox Engine error code.
  58.  
  59.  
  60.    char *ErrMsg();
  61.  
  62.        Returns a pointer to a string containing an error message
  63.        describing the result of the last operation on this object.
  64.  
  65.  
  66.    Object Evaluation
  67.  
  68.    The ! operator and the (void *) operator have been overloaded so
  69.    you can test an instance of the PXOBJ or a derived class for
  70.    validity.  A non-zero result indicates that the last operation on
  71.    the object was successful.  A zero result indicates that the last
  72.    operation was not successful, and you should examine the result
  73.    of Result() or ErrMsg() to determine the cause of the error.
  74.  
  75.    For example:
  76.  
  77.        PXTABLE mytable("mytable");
  78.        if(!mytable)
  79.            {
  80.            cout << mytable.ErrMsg();
  81.            exit(mytable.Result());
  82.            }
  83.  
  84.    Class PXTABLE
  85.  
  86.    This class is used to represent a Paradox table.  An object of
  87.    this class may be defined to open an existing table or to create
  88.    a new table.  Destruction of a PXTABLE object causes the
  89.    associated table to be closed.
  90.  
  91.    Constructors:
  92.  
  93.    PXTABLE(char *name, int index = 0, int saveEveryChange = FALSE);
  94.  
  95.        Use this constructor to open an existing table.  Refer to the
  96.        PXTblOpen() function in the Paradox Engine for information on
  97.        the index and saveEveryChange parameters.
  98.  
  99.  
  100.    PXTABLE(char *name, int nFlds, char **fldnames, char **types, int
  101.            saveEveryChange = FALSE);
  102.  
  103.        Use this constructor to create a new table.  Once created,
  104.        the table will be opened.  Be sure to test for success.
  105.  
  106.    Methods:
  107.  
  108.    int Name(int bufSize, char *namestr);
  109.  
  110.        Retrieves the name of the table.  bufSize is the lenth of the
  111.        buffer which namestr points to.
  112.  
  113.  
  114.    RECORDNUMBER NRecs();
  115.  
  116.        Returns the number of records in the table.
  117.  
  118.  
  119.    int NFlds();
  120.  
  121.        Returns the number of fields in the table.
  122.  
  123.  
  124.    int KeyNFlds();
  125.  
  126.        Returns the number of key fields in the table.
  127.  
  128.  
  129.    int RecLocked();
  130.  
  131.        Returns a non-zero value if the current record in the table
  132.        is locked.
  133.  
  134.  
  135.    int Changed();
  136.  
  137.        Tests whether the table has been changed.
  138.  
  139.  
  140.    int Lock(int lockType);
  141.  
  142.        Places a lock of the specified type on the entire table.
  143.        Returns the Paradox Engine error code (0 = success).
  144.  
  145.  
  146.    int Unlock(int lockType);
  147.  
  148.        Removes a lock of the specified type from the table.  Returns
  149.        the Paradox Engine error code.
  150.  
  151.  
  152.    int Refresh()
  153.  
  154.        Re-synchronizes the table.  Returns the Paradox Engine error
  155.        code.
  156.  
  157.  
  158.    int RecDelete();
  159.  
  160.        Deletes the current record from the table.  The current
  161.        record can be selected with either the PXTABLE class or the
  162.        PXRECORD class, so use caution.  Returns the Paradox Engine
  163.        result code.
  164.  
  165.  
  166.    int First();
  167.  
  168.        Moves the current record pointer to the first record in the
  169.        table.  The current record pointer can be moved with either
  170.        the PXTABLE class or the PXRECORD clas, so use caution.
  171.        Returns the Paradox Engine result code.
  172.  
  173.  
  174.    int Last();
  175.  
  176.        Moves the current record pointer to the last record in the
  177.        table.  The current record pointer can be moved with either
  178.        the PXTABLE class or the PXRECORD class, so use caution.
  179.        Returns the Paradox Engine result code.
  180.  
  181.  
  182.    int Next();
  183.  
  184.        Moves the current record pointer to the next record in the
  185.        table.  The current record pointer can be moved with either
  186.        the PXTABLE class or the PXRECORD class, so use caution.
  187.        Returns the Paradox Engine result code.
  188.  
  189.  
  190.    int Prev();
  191.  
  192.        Moves the current record pointer to the previous record in
  193.        the table.  The current record pointer can be moved with
  194.        either the PXTABLE class or the PXRECORD class, so use
  195.        caution.  Returns the Paradox Engine result code.
  196.  
  197.  
  198.    RECORDNUMBER RecNum();
  199.  
  200.        Returns the current record number.  Because Paradox is a
  201.        multi-user database, this number may not reflect the same
  202.        data at different times, so use with caution.
  203.  
  204.  
  205.    int Goto(RECORDNUMBER recnum);
  206.  
  207.        Moves the current record pointer to the specified record
  208.        number.  Returns the Paradox Engine result code.
  209.  
  210.  
  211.    Class PXFIELD
  212.  
  213.    This class is used to represent fields within a table.  Create an
  214.    object of this type for each field you wish to access.
  215.  
  216.    Constructors:
  217.  
  218.  
  219.    PXFIELD(PXTABLE &pxtable, char *fldname);
  220.  
  221.        Creates a PXFIELD object using a PXTABLE object.  Specify the
  222.        PXTABLE object and the name of the field.
  223.  
  224.  
  225.    PXFIELD(TABLEHANDLE th, char *fldname);
  226.  
  227.        Creates a PXFIELD object using a table handle.  Specify the
  228.        table handle and the name of the field.
  229.  
  230.  
  231.    FIELDHANDLE FldHandle();
  232.  
  233.        Returns the field handle of the object.
  234.  
  235.  
  236.    int FldName(int bufSize, char *buffer);
  237.  
  238.        Retrieves the name of the field.  <bufSize> is the maximum
  239.        length of the buffer to which <buffer> points.
  240.  
  241.  
  242.    int FldBlank();
  243.  
  244.        Tests if the field value for the current record is blank.
  245.        The current record pointer can be moved by an object of
  246.        either the PXTABLE class or the PXRECORD class, so use
  247.        caution.
  248.  
  249.  
  250.    int FldType(int bufSize, char *type);
  251.  
  252.        Retrieves the field type of the object.  <bufSize> is the
  253.        maximum size of the buffer to which <type> points.
  254.  
  255.    Class PXRECORD
  256.  
  257.    Objects of this class represent independent record transfer
  258.    buffers.  At least one is required for most table operations.
  259.    When performing field-level operations, a PXFIELD object or a
  260.    FIELDHANDLE is required for each individual field to be acted
  261.    upon.
  262.  
  263.    Constructors:
  264.  
  265.    PXRECORD(PXTABLE &pxtable);
  266.  
  267.        Creates a PXRECORD object for the specified table.
  268.  
  269.  
  270.    PXRECORD(TABLEHANDLE th);
  271.  
  272.        Creates a PXRECORD object for the specified table handle.
  273.  
  274.  
  275.    PXRECORD(PXRECORD &sourcerec);
  276.  
  277.        Creates a PXRECORD object from an existing PXRECORD object.
  278.        The new object is tied to the same table as the original
  279.        object, and the contents of the original record transfer
  280.        buffer are copied to the new object.
  281.  
  282.    Methods:
  283.  
  284.    RECORDHANDLE RecordHandle();
  285.  
  286.        Returns the record handle.
  287.  
  288.  
  289.    int NFlds(void);
  290.  
  291.        Returns the number of fields in the table.
  292.  
  293.  
  294.    int Append();
  295.  
  296.        Appends the contents of the record transfer buffer to the end
  297.        of the table.  Returns the Paradox Engine result code.
  298.  
  299.  
  300.    int Update();
  301.  
  302.        Updates the current record with the contents of the record
  303.        transfer buffer.  Returns the Paradox Engine result code.
  304.  
  305.  
  306.    int RecGet();
  307.  
  308.        Places the contents of the current record into the record
  309.        transfer buffer.  Returns the Paradox Engine result code.
  310.  
  311.  
  312.    int Insert();
  313.  
  314.        Inserts a new record into the table using the contents of the
  315.        record transfer buffer.  Returns the Paradox Engine result
  316.        code.
  317.  
  318.  
  319.    int Empty();
  320.  
  321.        Empties the contents of the record transfer buffer.  Returns
  322.        the Paradox Engine result code.
  323.  
  324.  
  325.    int Delete();
  326.  
  327.        Deletes the current record from the table.  The current
  328.        record pointer can be moved by an object of either the
  329.        PXTABLE class or the PXRECORD class, so use caution.
  330.  
  331.  
  332.    RECORDNUMBER RecNum();
  333.  
  334.        Returns the current record number.
  335.  
  336.  
  337.    int Goto(RECORDNUMBER recnum);
  338.  
  339.        Moves the current record pointer to the specified record
  340.        number.  Returns the Paradox Engine result code.
  341.  
  342.  
  343.    int First();
  344.  
  345.        Moves the current record pointer to the first record in the
  346.        table.  The current record pointer can be moved with either
  347.        the PXTABLE class or the PXRECORD class, so use caution.
  348.        Returns the Paradox Engine result code.
  349.  
  350.  
  351.    int Last();
  352.  
  353.        Moves the current record pointer to the last record in the
  354.        table.  The current record pointer can be moved with either
  355.        the PXTABLE class or the PXRECORD class, so use caution.
  356.        Returns the Paradox Engine result code.
  357.  
  358.  
  359.    int Next();
  360.  
  361.        Moves the current record pointer to the next record in the
  362.        table.  The current record pointer can be moved with either
  363.        the PXTABLE class or the PXRECORD class, so use caution.
  364.        Returns the Paradox Engine result code.
  365.  
  366.  
  367.    int Prev();
  368.  
  369.        Moves the current record pointer to the previous record in
  370.        the table.  The current record pointer can be moved with
  371.        either the PXTABLE class or the PXRECORD class, so use
  372.        caution.  Returns the Paradox Engine result code.
  373.  
  374.  
  375.    int SrchFld(PXFIELD &field, int scope = SEARCHFIRST);
  376.  
  377.        Searches the specified field using the contents of the record
  378.        transfer buffer.  Optionally, you may specify a FIELDHANDLE
  379.        instead of a PXFIELD object.  Returns the Paradox Engine
  380.        result code.
  381.  
  382.  
  383.    int SrchKey(int nFlds, int scope = SEARCHFIRST)
  384.  
  385.        Searches using the specified number of key fields and the
  386.        contents of the record transfer buffer.  Returns the Paradox
  387.        Engine result code.
  388.  
  389.  
  390.    int Put(PXFIELD &field);
  391.  
  392.        Puts a blank into the specified field of the record transfer
  393.        buffer.  You may optionally specify a FIELDHANDLE instead of
  394.        a PXFIELD object.  Returns the Paradox Engine result code.
  395.  
  396.  
  397.    int Put(PXFIELD &field, short s);
  398.  
  399.        Puts a short integer into the specified field of the record
  400.        transfer buffer.  You may optionally specify a FIELDHANDLE
  401.        instead of a PXFIELD object.  Returns the Paradox Engine
  402.        result code.
  403.  
  404.  
  405.    int Put(PXFIELD &field, long l);
  406.  
  407.        Puts either a long integer or a date into the specified field
  408.        of the record transfer buffer.  You may optionally specify a
  409.        FIELDHANDLE instead of a PXFIELD object.  Returns the Paradox
  410.        Engine result code.
  411.  
  412.    int Put(PXFIELD &field, double d);
  413.  
  414.        Puts a double into the specified field of the record transfer
  415.        buffer.  You may optionally specify a FIELDHANDLE instead of
  416.        a PXFIELD object.  Returns the Paradox Engine result code.
  417.  
  418.  
  419.    int Put(PXFIELD &fiekd, int m, int d, int y);
  420.  
  421.        Puts a date into the specified field of the record transfer
  422.        buffer.  You may optionally specify a FIELDHANDLE instead of
  423.        a PXFIELD object.  Returns the Paradox Engine result code.
  424.  
  425.  
  426.    int Put(PXFIELD &field, char *a);
  427.  
  428.        Puts a string into the specified field of the record transfer
  429.        buffer.  You may optionally specify a FIELDHANDLE instead of
  430.        a PXFIELD object.  Returns the Paradox Engine result code.
  431.  
  432.  
  433.    int Get(PXFIELD &field, short &s);
  434.    int Get(PXFIELD &field, long &l);
  435.    int Get(PXFIELD &field, double &d);
  436.    int Get(PXFIELD &field, int bufSize, char *a);
  437.    int Get(PXFIELD &field, int &m, int &d, int &y);
  438.  
  439.        Retreives the contents of the specified field from the record
  440.        transfer buffer.  You may optionally specify a FIELDHANDLE
  441.        instead of a PXFIELD object.  Specify a reference to a long
  442.        integer for either a numeric field or a date field.  Returns
  443.        the Paradox Engine result code.
  444.  
  445.    Operators:
  446.  
  447.    Operator =(PXRECORD &sourceRec);
  448.  
  449.        Use the assignment operator to copy the contents of one
  450.        record transfer buffer to another.  The two record transfer
  451.        buffers do not need to be tied to the same table, but the
  452.        structure of the tables must be identical.
  453.  
  454.    Class PXLOCK
  455.  
  456.    Each object of this class represents a lock on a record in the
  457.    specified table.  A PXLOCK can constructed using either a PXTABLE
  458.    object or a PXRECORD object.  In either case the lock is placed
  459.    on the current record in the table.  Be sure to test for success
  460.    after creating a PXLOCK object.  A lock may be removed by the
  461.    destruction of the object or by using the Unlock() method.
  462.  
  463.    Constructors:
  464.  
  465.  
  466.    PXLOCK(PXTABLE &pxtable);
  467.  
  468.        Places a lock on the current record in the specified table.
  469.  
  470.  
  471.    PXLOCK(PXRECORD &pxrecord);
  472.  
  473.        Places a lock on the current record in the table associated
  474.        with the PXRECORD object.
  475.  
  476.    Methods:
  477.  
  478.    LOCKHANDLE LockHandle();
  479.  
  480.        Returns the lock handle of the object.
  481.  
  482.  
  483.    int Unlock();
  484.  
  485.        Attempts to remove the lock.  Returns the Paradox Engine
  486.        result code.
  487.  
  488.  
  489.    int Goto();
  490.  
  491.        Moves the current record pointer to the locked record.
  492.        Returns the Paradox Engine result code.
  493.  
  494.    Using PDXPP
  495.  
  496.    All you need is PDXPP.H.  Just include it in your source code and
  497.    use it.  All functions and methods are inline.  It is not
  498.    necessary to include PXENGTCL.H as well.
  499.  
  500.  
  501.    Sample Program
  502.  
  503.    #include <iostreams.h>
  504.    #include "pdxpp.h"
  505.  
  506.    void main()
  507.    {
  508.        if(PXInit() != PXSUCCESS)
  509.            {
  510.            cout << "Unable to initialize the engine!";
  511.            exit(1);
  512.            }
  513.  
  514.        PXTABLE payments("payments");
  515.        if(!payments)
  516.            {
  517.            cout << "Unable to open table.";
  518.            exit(1);
  519.            }
  520.  
  521.        PXRECORD rtb(payments);
  522.  
  523.        PXFIELD fInvNum(payments, "Inv #");
  524.        PXFIELD fAmount(payments, "amount");
  525.        PXFIELD fCheckDate(payments, "Check Date");
  526.        PXFIELD fCheckNum(payments, "Check #");
  527.  
  528.        short invNum;
  529.        long checkNum;
  530.        int m,d,y;
  531.        double amount;
  532.  
  533.        for(rtb.First(); rtb; rtb.Next())
  534.            {
  535.            rtb.Get(fInvNum, invNum);
  536.            rtb.Get(fAmount, amount);
  537.            rtb.Get(fCheckDate, m, d, y);
  538.            rtb.Get(fCheckNum, checkNum);
  539.  
  540.            cout << invNum << fCheckNum << m << d << y%100 << amount;
  541.            cout << nl;
  542.            }
  543.  
  544.        PXExit();
  545.    }
  546.  
  547.    Appendix 1: Paradox Engine Functions not represented.
  548.  
  549.    PXExit
  550.    PXGetDefaults
  551.    PXInit
  552.    PXKeyAdd
  553.    PXKeyDrop
  554.    PXNetErrUser
  555.    PXNetInit
  556.    PXNetUserName
  557.    PXPswAdd
  558.    PXPswDel
  559.    PXSetDefaults
  560.    PXSetHWHandler
  561.    PXTblAdd
  562.    PXTblCopy
  563.    PXTblDecrypt
  564.    PXTblDelete
  565.    PXTblEmpty
  566.    PXTblEncrypt
  567.    PXTblExist
  568.    PXTblMaxSize
  569.    PXTblProtected
  570.    PXTblRename
  571.  
  572.